ZendeskのWeb API経由でトリガの設定を確認・更新する方法

#Zendesk

入井啓太

2023.06.24

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

こんにちは、ゲームソリューショングループの入井です。

Zendeskでは、トリガを設定することによって、一定の条件を満たした際に様々な処理をオートメーションで実行することが可能です。

トリガは非常に便利な機能である反面、その設定内容は複雑になりがちで、現在どのような設定がされているのかの把握が難しく、設定確認のためにいちいちGUIの管理画面を開くのも手間がかかります。また、他の管理者によって設定が変えられていても、それに気づくことは難しいです。

トリガは、Zendeskが用意しているWeb APIから設定内容の確認・更新が可能です。細かな条件や処理の内容まですべてJSONによってテキストで表現されているので、上手くAPIを活用すれば設定内容を自動的にドキュメント化する仕組みが作成できます。例えば、設定内容をGitで管理するような仕組みを作れば、変更の差分を後からでも把握できるようになります。

なお、Zendesk APIを使用するための認証の方法については、以下の記事を参考にしてください。

APIリクエストを認証するにはどうすればよいですか？ – Zendeskヘルプ

トリガへのWeb APIでのアクセス

取得

トリガの設定内容を取得するには、以下のエンドポイントにアクセスします。

GET https://[subdomain].zendesk.com/api/v2/triggers
- トリガをリスト形式で取得
GET https://[subdomain].zendesk.com/api/v2/triggers[trigger_id]
- 指定したIDのトリガを単体取得

トリガのレスポンス形式は、以下のような形です。

{
      "url": "https://[subdomain].zendesk.com/api/v2/triggers/111111.json",
      "id": 111111,
      "title": "担当者への通知 - 割り当て",
      "active": false,
      "updated_at": "2023-01-10T09:11:01Z",
      "created_at": "2020-04-15T09:26:21Z",
      "default": false,
      "actions": [
          {
              "field": "notification_user",
              "value": [
                  "assignee_id",
                  "[{{ticket.account}}] 割り当て: {{ticket.title}}",
                  "あなたはこのチケット（No.#{{ticket.id}}）の担当者になりました。\n\n{{ticket.comments_formatted}}"
              ]
          }
      ],
      "conditions": {
          "all": [
              {
                  "field": "assignee_id",
                  "operator": "changed",
                  "value": null
              },
              {
                  "field": "assignee_id",
                  "operator": "is_not",
                  "value": "current_user"
              }
          ],
          "any": []
      },
      "description": null,
      "position": 8,
      "raw_title": "担当者への通知 - 割り当て",
      "category_id": "999999"
  }

こちらは、実際に弊社のZendesk検証環境内に設定されているトリガから取得した情報です。チケットの担当者として割り当てられたエージェントに対し、メールで通知を送るトリガです。

“conditions”内にトリガの実行条件が書かれています。”all”内の条件を全て満たし”any”内の条件のいずれかを満たした際にアクションが実行される形です。

  {
      "field": "assignee_id",
      "operator": "changed",
      "value": null
  },

こちらは、「担当者が変更された」を意味する条件です。値の設定は必要ないので"value"がnullとなっています。

 {
      "field": "assignee_id",
      "operator": "is_not",
      "value": "current_user"
  }

こちらは、「担当者がチケット更新を行ったユーザーではない」を意味する条件です。自分でチケット担当者を自分に割り当てた際は通知の必要がないため、この条件が入っています。

実行されるアクションについては、”actions”に入っています。

  {
      "field": "notification_user",
      "value": [
          "assignee_id",
          "[{{ticket.account}}] 割り当て: {{ticket.title}}",
          "あなたはこのチケット（No.#{{ticket.id}}）の担当者になりました。\n\n{{ticket.comments_formatted}}"
      ]
  }

“notification_user”はメール通知の実行を表し、具体的な内容は”value”配列内で通知対象、メール件名、メール本文という順番で設定されています。{{ticket.account}}などはプレースホルダーです。実際のアクション実行時は、対応したテキストが動的に割り当てられます。

なお、こちらのトリガ設定を管理画面上で見ると以下の画像のような形となっています。